//+------------------------------------------------------------------+
//|                ChartObjectsGann.mqh MQL5 江恩工具头文件           |
//|                版权所有 2000-2025, MetaQuotes Ltd.              |
//|                        官方网址: https://www.mql5.com            |
//+------------------------------------------------------------------+
//| 包含所有江恩（Gann）技术分析工具类（江恩线、江恩扇形、江恩网格）      |
//+------------------------------------------------------------------+
#include "ChartObjectsLines.h"  // 引入趋势线相关基类（CChartObjectTrend、CChartObjectTrendByAngle）

//+------------------------------------------------------------------+
//| CChartObjectGannLine 类（江恩线工具）                            |
//| 功能：MQL5 图表江恩线工具，基于“时间-价格等同”原则的趋势线，用于识别关键支撑/阻力 |
//| 继承关系：public CChartObjectTrendByAngle（基于“按角度绘制的趋势线”基类，支持角度控制）|
//| 核心特性：                                                      |
//|  1. 角度驱动：通过“点差/每根K线（PipsPerBar）”计算角度，体现时间与价格的平衡关系 |
//|  2. 关键角度：默认包含 45°（1x1 角度，代表1单位时间对应1单位价格变动）等江恩核心角度 |
//|  3. 趋势跟踪：适用于识别强趋势中的关键价位，价格沿江恩线运动时视为趋势延续 |
//+------------------------------------------------------------------+
class CChartObjectGannLine : public CChartObjectTrendByAngle
  {
public:
   /**
    * @brief 构造函数：初始化江恩线对象
    * @details 调用父类 CChartObjectTrendByAngle 构造函数，初始化角度趋势线基础属性（未绑定图表）
    */
                     CChartObjectGannLine(void);

   /**
    * @brief 析构函数：销毁江恩线对象
    * @details 依赖父类析构逻辑，自动删除图表上的江恩线对象，释放资源
    */
                    ~CChartObjectGannLine(void);

   //--- 江恩线特有属性接口（点差/每根K线，用于计算角度）
   /**
    * @brief 获取“点差/每根K线”参数（江恩线角度的核心计算依据）
    * @return double - 点差/每根K线值（如 0.001 表示每根K线对应 10 个点差，具体需结合品种点差单位）
    * @note 该参数决定江恩线角度：值越大，线条越陡峭（相同时间内价格变动越大）
    */
   double            PipsPerBar(void) const;

   /**
    * @brief 设置“点差/每根K线”参数
    * @param ppb [in] 新的点差/每根K线值（建议根据品种波动性设置，如 EURUSD 可设 0.0005~0.002）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定图表）
    */
   bool              PipsPerBar(const double ppb) const;

   //--- 江恩线创建接口
   /**
    * @brief 在指定图表创建江恩线（通过时间锚点与点差参数定义）
    * @param chart_id [in] 目标图表 ID（0 表示当前图表，可通过 ChartID() 获取）
    * @param name [in] 江恩线对象唯一名称（图表内不可重复）
    * @param window [in] 子窗口编号（0=主窗口，≥1=指标子窗口）
    * @param time1 [in] 第1个锚点的时间坐标（江恩线起点对应的 K 线时间，如趋势启动时间）
    * @param price1 [in] 第1个锚点的价格坐标（江恩线起点对应的价格，如趋势启动价格）
    * @param time2 [in] 第2个锚点的时间坐标（江恩线延伸的目标时间，用于确定线条长度）
    * @param ppb [in] 点差/每根K线参数（用于计算江恩线角度，核心参数）
    * @return bool - 操作结果：true 表示创建成功（对象创建+绑定+角度参数设置完成），false 表示失败
    * @note 第2个锚点仅影响线条显示长度，不改变角度；角度由 PipsPerBar 自动计算（如 ppb=0.001 对应 45° 线）
    */
   bool              Create(long chart_id,const string name,const int window,
                            const datetime time1,const double price1,
                            const datetime time2,const double ppb);

   //--- 对象类型标识（重写基类方法）
   /**
    * @brief 获取江恩线对象类型（MQL5 预定义类型）
    * @return int - 对象类型标识（返回 OBJ_GANNLINE，代表江恩线工具）
    */
   virtual int       Type(void) const { return(OBJ_GANNLINE); }

   //--- 序列化接口（重写基类方法，扩展江恩线特有属性的读写）
   /**
    * @brief 将江恩线参数（含特有属性）保存到文件
    * @param file_handle [in] 文件句柄（需提前以 FILE_WRITE 模式打开）
    * @return bool - 操作结果：true 表示保存成功，false 表示失败（文件无效/未绑定图表）
    * @note 保存内容：基类角度趋势线属性 + 点差/每根K线（PipsPerBar）参数
    */
   virtual bool      Save(const int file_handle);

   /**
    * @brief 从文件加载江恩线参数（含特有属性）
    * @param file_handle [in] 文件句柄（需提前以 FILE_READ 模式打开）
    * @return bool - 操作结果：true 表示加载成功，false 表示失败（文件无效/未绑定图表）
    */
   virtual bool      Load(const int file_handle);
  };

//+------------------------------------------------------------------+
//| CChartObjectGannFan 类（江恩扇形工具）                            |
//| 功能：MQL5 图表江恩扇形工具，由多根江恩线组成扇形，覆盖趋势中的多个关键角度 |
//| 继承关系：public CChartObjectTrend（基于基础趋势线基类，支持多线组合）|
//| 核心特性：                                                      |
//|  1. 多角度覆盖：包含 1x8（7.5°）、1x4（15°）、1x2（30°）、1x1（45°）、2x1（60°）等核心江恩角度 |
//|  2. 趋势方向控制：支持上升/下降趋势切换（Downtrend 属性），自动调整扇形开口方向 |
//|  3. 区间分析：价格在扇形线之间运动时视为趋势正常波动，突破扇形边界视为趋势反转信号 |
//+------------------------------------------------------------------+
class CChartObjectGannFan : public CChartObjectTrend
  {
public:
   /**
    * @brief 构造函数：初始化江恩扇形对象
    * @details 调用父类 CChartObjectTrend 构造函数，初始化趋势线组合基础属性（未绑定图表）
    */
                     CChartObjectGannFan(void);

   /**
    * @brief 析构函数：销毁江恩扇形对象
    * @details 依赖父类析构逻辑，自动删除图表上的扇形线组合，释放资源
    */
                    ~CChartObjectGannFan(void);

   //--- 江恩扇形特有属性接口（点差参数、趋势方向）
   /**
    * @brief 获取“点差/每根K线”参数（所有扇形线的角度计算依据）
    * @return double - 点差/每根K线值（与江恩线的 PipsPerBar 定义一致）
    */
   double            PipsPerBar(void) const;

   /**
    * @brief 设置“点差/每根K线”参数（统一控制所有扇形线的角度）
    * @param ppb [in] 新的点差/每根K线值（建议与品种波动性匹配）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定图表）
    */
   bool              PipsPerBar(const double ppb) const;

   /**
    * @brief 获取趋势方向（上升/下降）
    * @return bool - 趋势方向：true=下降趋势（扇形开口向下），false=上升趋势（扇形开口向上）
    */
   bool              Downtrend(void) const;

   /**
    * @brief 设置趋势方向（切换扇形开口方向）
    * @param downtrend [in] 新趋势方向（true=下降，false=上升）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定图表）
    * @note 趋势方向改变后，所有扇形线的角度会自动反向，适配新趋势
    */
   bool              Downtrend(const bool downtrend) const;

   //--- 江恩扇形创建接口
   /**
    * @brief 在指定图表创建江恩扇形（通过时间锚点与点差参数定义）
    * @param chart_id [in] 目标图表 ID
    * @param name [in] 扇形对象唯一名称
    * @param window [in] 子窗口编号
    * @param time1 [in] 第1个锚点的时间坐标（扇形公共起点时间，如趋势转折点）
    * @param price1 [in] 第1个锚点的价格坐标（扇形公共起点价格，如趋势转折点价格）
    * @param time2 [in] 第2个锚点的时间坐标（扇形延伸的目标时间，用于确定扇形大小）
    * @param ppb [in] 点差/每根K线参数（控制所有扇形线的角度）
    * @return bool - 操作结果：true 表示创建成功（对象创建+绑定+点差设置完成），false 表示失败
    * @note 第1个锚点为所有扇形线的公共起点；默认创建上升趋势扇形，可通过 Downtrend 方法切换为下降趋势
    */
   bool              Create(long chart_id,const string name,const int window,
                            const datetime time1,const double price1,
                            const datetime time2,const double ppb);

   //--- 对象类型标识（重写基类方法）
   /**
    * @brief 获取江恩扇形对象类型（MQL5 预定义类型）
    * @return int - 对象类型标识（返回 OBJ_GANNFAN，代表江恩扇形工具）
    */
   virtual int       Type(void) const { return(OBJ_GANNFAN); }

   //--- 序列化接口（重写基类方法，扩展扇形特有属性的读写）
   /**
    * @brief 将江恩扇形参数（含特有属性）保存到文件
    * @param file_handle [in] 文件句柄
    * @return bool - 操作结果：true 表示保存成功，false 表示失败
    * @note 保存内容：基类趋势线属性 + 点差/每根K线（PipsPerBar） + 趋势方向（Downtrend）
    */
   virtual bool      Save(const int file_handle);

   /**
    * @brief 从文件加载江恩扇形参数（含特有属性）
    * @param file_handle [in] 文件句柄
    * @return bool - 操作结果：true 表示加载成功，false 表示失败
    */
   virtual bool      Load(const int file_handle);
  };

//+------------------------------------------------------------------+
//| CChartObjectGannGrid 类（江恩网格工具）                            |
//| 功能：MQL5 图表江恩网格工具，由水平+垂直江恩线组成网格，覆盖时间与价格的关键区间 |
//| 继承关系：public CChartObjectTrend（基于基础趋势线基类，支持网格状线组合）|
//| 核心特性：                                                      |
//|  1. 时空网格：水平线条对应价格关键位，垂直线条对应时间关键节点，形成“时间-价格”网格 |
//|  2. 趋势适配：支持上升/下降趋势切换（Downtrend 属性），网格密度由点差参数控制 |
//|  3. 区间定位：适用于精确定位趋势中的支撑/阻力位与时间窗口，网格交点为强关键位 |
//+------------------------------------------------------------------+
class CChartObjectGannGrid : public CChartObjectTrend
  {
public:
   /**
    * @brief 构造函数：初始化江恩网格对象
    * @details 调用父类 CChartObjectTrend 构造函数，初始化趋势线组合基础属性（未绑定图表）
    */
                     CChartObjectGannGrid(void);

   /**
    * @brief 析构函数：销毁江恩网格对象
    * @details 依赖父类析构逻辑，自动删除图表上的网格线组合，释放资源
    */
                    ~CChartObjectGannGrid(void);

   //--- 江恩网格特有属性接口（与江恩扇形一致，复用逻辑）
   /**
    * @brief 获取“点差/每根K线”参数（控制网格线条的密度与角度）
    * @return double - 点差/每根K线值（与江恩线、江恩扇形的 PipsPerBar 定义一致）
    */
   double            PipsPerBar(void) const;

   /**
    * @brief 设置“点差/每根K线”参数（统一控制网格的密度）
    * @param ppb [in] 新的点差/每根K线值（值越小，网格越密集）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定图表）
    */
   bool              PipsPerBar(const double ppb) const;

   /**
    * @brief 获取趋势方向（上升/下降）
    * @return bool - 趋势方向：true=下降趋势（网格倾斜向下），false=上升趋势（网格倾斜向上）
    */
   bool              Downtrend(void) const;

   /**
    * @brief 设置趋势方向（切换网格倾斜方向）
    * @param downtrend [in] 新趋势方向（true=下降，false=上升）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定图表）
    */
   bool              Downtrend(const bool downtrend) const;

   //--- 江恩网格创建接口
   /**
    * @brief 在指定图表创建江恩网格（通过时间锚点与点差参数定义）
    * @param chart_id [in] 目标图表 ID
    * @param name [in] 网格对象唯一名称
    * @param window [in] 子窗口编号
    * @param time1 [in] 第1个锚点的时间坐标（网格起点时间，如趋势启动时间）
    * @param price1 [in] 第1个锚点的价格坐标（网格起点价格，如趋势启动价格）
    * @param time2 [in] 第2个锚点的时间坐标（网格延伸的目标时间，用于确定网格大小）
    * @param ppb [in] 点差/每根K线参数（控制网格线条的密度与角度）
    * @return bool - 操作结果：true 表示创建成功（对象创建+绑定+点差设置完成），false 表示失败
    * @note 第1个锚点为网格的“原点”，所有水平/垂直线条均从此点按江恩角度延伸；默认创建上升趋势网格
    */
   bool              Create(long chart_id,const string name,const int window,
                            const datetime time1,const double price1,
                            const datetime time2,const double ppb);

   //--- 对象类型标识（重写基类方法）
   /**
    * @brief 获取江恩网格对象类型（MQL5 预定义类型）
    * @return int - 对象类型标识（返回 OBJ_GANNGRID，代表江恩网格工具）
    */
   virtual int       Type(void) const { return(OBJ_GANNGRID); }

   //--- 序列化接口（重写基类方法，扩展网格特有属性的读写）
   /**
    * @brief 将江恩网格参数（含特有属性）保存到文件
    * @param file_handle [in] 文件句柄
    * @return bool - 操作结果：true 表示保存成功，false 表示失败
    * @note 保存内容：基类趋势线属性 + 点差/每根K线（PipsPerBar） + 趋势方向（Downtrend）
    */
   virtual bool      Save(const int file_handle);

   /**
    * @brief 从文件加载江恩网格参数（含特有属性）
    * @param file_handle [in] 文件句柄
    * @return bool - 操作结果：true 表示加载成功，false 表示失败
    */
   virtual bool      Load(const int file_handle);
  };
//+------------------------------------------------------------------+